Orders API icon

Orders API

1.8.x
(0 reviews)

Enabling Webhook Delivery

When placing orders through LANDATA DDP, fulfilled products are delivered via email by default. You can also choose to receive webhook notifications upon product fulfillment. This guide outlines the steps and requirements for enabling webhook delivery.

Requirements

1) Webhook Endpoint

What is the URL of the webhook endpoint? The notification messages will be sent to this URL.

2) Webhook Authentication

a) HMAC Signature

Will you be using an HMAC signature for authentication? If so, please specify whether you will provide the secret key to generate the signature, or if SERV should provide it. See Authentication Mechanisms: HMAC Signature section below for details on how this works.

b) Token Authentication

Does your webhook URL require token authentication? If so, please provide all the necessary details for authentication. See Authentication Mechanisms: Token Authentication section below for more details.

You will need to provide instructions on how to get the bearer token. For example, if you have a HTTP endpoint, specify the request parameters and how to send the request parameters. Below are common parameters usually required for an authentication URL:

  • Authentication URL
  • Client ID
  • Client Secret
  • Content Type (application/json, application/x-www-form-urlencoded, etc.)
    • If content type is application/json, provide an example of the JSON body.
    • If content-type is application/x-www-form-urlencoded, provide the keys and values.
  • Audience
  • Grant Type

Onboarding Request

To initiate the onboarding, please send the requirements listed above to TheAtLANDeansSupport@servictoria.com.au

Authentication Mechanisms

LANDATA DDP supports two authentication mechanisms: HMAC signature and token authentication.

HMAC Signature

This mechanism uses a secret key to sign webhook requests, allowing the destination system to verify data integrity.

1) A secret key is shared between the webhook provider and SERV.

2) SERV uses this key and HMAC-SHA256 algorithm to generate a hash signature based on the webhook payload. The following is the Python code:

hmac.new(
    key=bytes(secret, "utf-8"),
    msg=payload, # bytes
    digestmod=hashlib.sha256,
).hexdigest()

3) The signature is included in the request header, named x-serv-signature, alongside the webhook request.

4) Upon receiving the request, the provider uses the same secret key and algorithm to compute a signature from the payload.

5) The computed signature is then compared to the one in the x-serv-signature header. If they match, the request is valid; if not, it is rejected.

Token Authentication

This mechanism includes an bearer token in the webhook requests, obtained through an initial authentication request.

1) The webhook provider shares authentication details (such as the authentication endpoint, client ID/secret) with SERV. See Requirements: Token Authentication for examples of authentication details.

2) SERV requests an access token from the authorisation server using these details. For example, a JSON request to the server could look like this:

{
  "client_id": "example_client_id",
  "client_secret": "example_client_secret",
  "audience": "https://example.com/webhook",
  "grant_type": "client_credentials"
}

3) The token is sent in the Authorization header of the webhook request, in the following format: Authorization: Bearer {token}

4) Upon receiving the request, the webhook provider validates the token. If valid, the request is processed; if not, it is rejected.

Reviews